====== cpgShop introduction ======
cpgShop is a shopping cart software for Coppermine 1.5.x that comes with PayPal support. It allows you to sell digital images for download or printed images that you snail mail to your customers.

====== cpgShop requirements ======
  * Of course cpgShop needs Coppermine 1.5.x to run.
  * For PDF support PDFlib (Lite) should be enabled on your server. PDF generation should work also with GD2 but it is more CPU intense and the result not as good.
  * Mandatory is the use of a ssl certificate to crypt the http protocoll (https) if you want to use the PayPal IPN feature.
  * If you use PayPal it also is mandatory for security reasons to use encrypted PayPal buttons. For that OpenSSL needs to be enabled in php.ini. Also you need to be able to generate your private key and public certificate. I recommend to download the openssl commandline tool for that. Later I'll explain howto generate the keys with this programm.

====== cpgShop limitations======
This version does not support
  * PayPal IPN (Instant Payment Notification) - when the customer has paid you manually have to mark the order paid
  * Download folders - you manually have to send the customers your digital images (either by email, http or ftp)
For a donation I will send you this modules.

====== cpgShop features ======
  * Sell downloadable pictures
  * Downloadable content resized on the fly
  * Password protected download folders
  * Sell for print pictures
  * Various shipping methods
  * Additional shipping fees for certain prices
  * Additional shipping fees for differnt countries
  * PayPal support
  * PayPal IPN
  * PayPal IPN logging
  * Encrypted PayPal buttons
  * Cash on delivery support
  * Wire transfer
  * Item options
  * Discounts (codes)
  * Customer needs to agree to TOS (optional)
  * Modified register page with mandatory address fields
  * Modified profile page to reflect this new fields
  * Easily make these fields not mandatory
  * All email templates can be modified in a web backend
  * Invoices (text, html, pdf)
  * Customer can be informed about order state changes
  * Workflow with virtual folders - incoming, paid, printed, processed.
  * On status changes orders can automatically be moved into their corresponding folders.
  * Customer has a order history
  * Customer can check the order status
  * Customer has the possibility to resend his download password and invoice
  * Customer can cancel orders as long the order state has not changed from incoming
  * Admin can lock the download folder
  * Admin can resend the download password
  * Admin can resend the invoice
  * Admin can delete the download folder

====== cpgShop installation ======
Upload the cpgshop directory and all files and subfolder to your Coppermine plugins directory leaving the folder structure intact. Log into Coppermine as admin and select in the menu config -> plugins. Now hit the install icon next to the cpgShop entry, confirm the database table generation and your ready to go.

====== cpgShop Config ======
===== General Shop Settings =====

== Enable cpgShop ==
(Yes/No) To enable/ disable the shop.

== Default cpgShop currency ==
Here you can select your currency. To avoid problems with PayPal this should be set to the same currency that you've chosenin your PayPal merchant account. At this time I've added USD, CAD, GBP, EUR, JPY. Other PayPal supported currencies can easily be added.

== cpgShop notify email ==
Add here the email address where cpgShop should send its notification emails

== Notify on new orders ==
(Yes/No) Enable to get notifications on new orders

== Tax fee type (shop country or customer based) ==
(Country/ Customer) The tax fee type I haven't implemented yet. A country based calculation is now used.

== Tax fee in % ==
Add here the tax percentage.

== Show a 'printed' process step in the order manager (in addition to paid, sent, downloaded) ==
(Yes/No) The order processing workflow usually contains three steps. Incoming orders, paid orders and downloaded/ sent orders. If you print and send your orders, you may wish to add one process step (virtual folder).

== Automatically move the orders into the corresponding virtual folders if the process step changes. ==
(Yes/No) If enabled cpgShop moves the orders into corresponding virtual folders. If a new order arrives, it is placed into the 'incoming' folder. If you mark it 'booked', cpgShop will move it into the booked folder etc.

== Email the customer on process step change ==
(Yes/No) Enable this if you want the customer to be informed when the pictures have been printed or sent.

== Enable download of purcheased images ==
(Yes/No) Needs to be enabled if you sell digital images for download.

== If downloads are enabled offer zip downloads, too ==
(Yes/No) Customers either have to download images one by one from their download folder or if you enable this setting a zip file's getting saved into their folder as well.

== Hours after the download folder should be auto deleted ==
If you want the download folders to be deleted after a certain time, then enter here the hours. Leave that field blank if you don't wish to clean the download directory. The cleanup function is always getting called when you open the order manager.

== Attatch a pdf invoice to the order confirmation email ==
(Yes/No) Customers egt sent a confirmation email with an inline invoice (html and text). Additionally you can attach a pdf invoice with this option.

== Enable -Order history- button. History of purcheases for customers ==
(Yes/No) A order history button appeares. Customers can check the status of their orders here. Also payment and download information can be found here as well. If you use PayPal as payment gateway it is recommended to enable this function as in the order confirmation email a link is placed as this area contains a 'Pay with PayPal' button.

== Show a calculate fees link in shopping basket (and on shipping type icons) ==
(Yes/No) The customer can check gateway and shipping fees here.

== Customer has to accept the TOS ==
(Yes/No) If enabled the customer has to click a checkbox and hence agrees to the TOS

== Customer can cancel orders ==
(Yes/No) You can allow the customer to cancel an order as long as he hasn't paid or you worked on the image. Of course the shop system needs to know the actual order state for this to properly work.


===== PayPal settings =====
== Enable PayPal gateway ==
(Yes/No) To enable/ disable the PayPal gateway

== If customer selects PayPal, only standard delivery is possible! ==
(Yes/No) If enabled the customer can only delect standard delivery as shipping method when paying with PayPal

== Your PayPal merchant email ==
Add here your PayPal merchant email

== Use the PayPal sandbox - no real transactions ==
(Yes/No) Before you start selling items test everything in the PayPal sandbox (highly recommended).

== Charge customers a fee to pay with PayPal ==
(Yes/No) If you want to charge customers using the PayPal gateway a fee, this option needs to be enabled.

== PayPal Fee ==
Add here the fee you want to charge

== Enable PayPal IPN (Instant Payment Notification) ==
(Yes/No) In case you want to use PayPal IPN enable this functionality. With IPN enabled PayPal sends back a notification to your site when the customer has paid. Further actions can be initiated like creating a download folder for the customer and sending him the password.
IPN needs to be enabled in your PayPal account, too.

== Enable additional txt file log ==
(Yes/No) PayPal IPN transactions getting logged in the MySQL database. If you want flat file logging as well enable this option.

== The path to the log file ==
Enter here the path to your log file. The default is saved in the Coppermine log directory.

== Enable SSL ==
(Yes/No) If you use PayPal IPN it is mandatory to use SSL encrytion. Talk to your host for a SSL certificate.

== SSL URL to coppermine base dir ==
If SSL is enabled enter here the SSL URL to the coppermine base dir (don't forget the trailing slash at the end)

== Encrypt the Paypal button ==
(Yes/No) Intsead of human readable hidden input fields the transaction details get encrypted. Mandatory if you use PayPal.

== Filename of PayPals public certificate ==
Enter here the filename of PayPal's public certificate

== Filename of your public certificate ==
Enter here the filename of your public certificate (you need to create that cert as well as your private key using OpenSSL)

== Filename of your private key ==
Enter here the filename of your private key

== Path to the keyfiles ==
Don't forget to add the path to your key and certs. By default the keys get saved in the keys folder in the plugin directory wher a htaccess file has been placed to avoid unauthorized access. Far better and recommended would be to place these keys outside of the web accessible area.

== Cert ID ==
After uploading your public key to PayPal you get acert ID. Enter it here.

===== Display wire transfer information =====
== Enable displaying wire information ==
(Yes/No) If you want the customer to be able to pay by wire transfer.

== If customer selects wire transfer, only standard delivery is possible! ==
(Yes/No) Equal setting to the one in the PayPal category. If enabled the customer can only chose standard delivery as shipping method.

== Charge customers a fee to pay using bank services ==
(Yes/No) If you want to charge a wire transaction fee enable this

== Wire transfer fee ==
Add here the fee

== Routing number ==
== Account number ==
== Bank name ==
== Bank address ==
== Bank SWIFT ==

===== Cash on delivery settings =====
== Cash on delivery enabled ==
(Yes/No) When sending prints you may want to enable cod as payment method

== If customer selects COD, only standard delivery is possible! ==
(Yes/No) If enabled only standard delivery as shipping method is possible

== Enable COD fee ==
(Yes/No) Needs to be enabled if you want to charge a fee for cod

== COD Fee ==
Enter here the fee you want to charge


===== Parcel delivery settings =====
== Enable a fee for standard delivery ==
(Yes/No) Standard delivery is always enabled. Enable the fee for standard delivery here.

== Fee for standard delivery ==

== Customers can pickup their items ==
(Yes/No) If you want to allow customers to come into your office and pick up their prints

== Enable pickup fee ==
(Yes/No)

== Pickup fee ==

== Enable express delivery ==
(Yes/No)

== Enable a fee for express delivery ==
(Yes/No)

== Fee for express delivery ==

== Enable UPS delivery ==
(Yes/No)

== Enable a fee for UPS ==
(Yes/No)

== Fee for UPS delivery ==


===== Discount settings =====
== Enable discount ==
(off/ by items purcheased / by basket value/ by code entered)

Here you can set different discount possibilities but only one at a time. They can'r be mixed.
  * By items purcheased - if customer buys a certain amount of items you can specify a discount
  * By basket value - if the basket value reaches a certain limit you can specify a discount
  * By code entered - you can create discount codes. Whilst checking out the customer can enter such a code and gets granted a specified discount value.
  *
== Trigger, when to apply the discount ==
(number of items or basket value) Add here the trigger when the discount should be granted. Eg. 50 items need to be bought by the customer or he needs to shop goods for 250,00 USD.

== Min. basket size in currency to apply discount ==
That's the minimum value that needs to be in the shopping basket before a discount's getting applied

== Discount ==
(fix amount or %) add here the discount value for -by items purcheased- and -by basket value-. If the trigger is reached this will be value. Either a fix number or a percentage.

== Lenght of discount code ==
If you want to use discount codes then you can here specify the code length.


====== cpgShop admin menu ======
You can open the cpgShop administration page by clicking in Coppermine's admin menu 'Config' -> 'Shop Manager'.

===== Stats =====
That's what you see when you open the Shop Manager. Some stats get dispalyed here like the number of new orders, unpaid, unsent and not printed orders. With just one click you can have a look at these groups in the order manager.

===== Price Manager =====
When setting up the shop this is usually where you beginn. All different prices you want to charge for items you need to add here. Let's add one. Click 'New price'. In the following mask fill in the fields. The title field is what's getting displayed later to the customer (eg. download 1024px).

Now assign a price to that item.
'Additional shipping' is meant for items that are not prints and are heavier or bigger and shipping therefore is more expensive. If you want to charge that extra shipping fee tehn add its price here.
Finally specify if the item is for print, you intend to send that item by snail mail, or if it's a download. That's it. We have added our first price.
In the overview you can mark certain prices. Clicking now 'delete' will remove them from the database.

===== Price Set Manager =====
In the price set manager you can group prices. Later on we assign such price sets to the images. Means, the price sets get shown to the customers. So you have to create price sets, even if you add just one price.

Again click 'New price set'. Now press 'control' on your keyboard and select all prices you want to group. Add the group name (title) so that you later can identify your price set and click 'add'.

===== Option Manager =====
If you need options, then this is the place to go. What is such a option I'm talking about. For example I'm selling cups. Then an option would be green, yellow or white. The customer can select the color. You can assign prices for the different options so that green is less expensive than yellow.

As in the price manager you need to create options. So hit 'New option' and fill in all fields.
In our example we would enter color for the title field. For the option titles we'd enter green|yellow|white and for the value eg. 1.50|2|1 (that's the additional prices for each option in the shops currency).

===== Option Set Manager =====
These options we need to group as we'd done with the prices. Even if you have only one option, you need to create a group as that is what you assign the images.

===== Countries =====
Here we add the countries we want to ship to. When checking out, the customers country's getting verified. If it's not in this country list, ordering fails. Click 'Add countries' and select all countries you want and click add. Now you can add different shipping fees to each country. When done don't forget to click 'Save new shipping fees'.


===== Discounts =====
That's the place to create discount codes. You can create discounts by just selecting the number of codes to create and entering the value. You can switch between active and used discounts. When viewing the used discounts, you can go to the corresponding order or user profile.


===== Documents =====
All document templates are located here. You can click them to modify them.

  * TOS: text that's getting displayed when the customer clicks the 'terms of service' link
  * state_change_sent_txt: txt email sent to the customer when ordering state changes (order sent)
  * state_change_sent_subj: the subject for the above email
  * state_change_sent_html: the above email in the html version. Make sure to edit text and html version cause both get sent to the customer. Depending on his email client the one is shown or the other.
  * state_change_printed_txt: txt email sent to the customer when ordering state changes (printed)
  * state_change_printed_subj
  * state_change_printed_html
  * state_change_paid_txt: txt email sent to the customer when ordering state changes (paid)
  * state_change_paid_subj
  * state_change_paid_html
  * state_change_downloaded_txt: txt email sent to the customer when ordering state changes (downloaded)
  * state_change_downloaded_subj
  * state_change_downloaded_html
  * ipn_admin_mail_txt: that's an email to the admin. It contains IPN information
  * htaccess: the htaccess file that's written to the download directory
  * email_password_user_txt: the email the customer gets when the download folder has been created
  * email_password_user_subj
  * email_password_user_html
  * email_checkout_user_txt: txt email sent to the customer with his order confirmation and invoice
  * email_checkout_user_pdf: the template for the pdf invoice
  * email_checkout_user_html
  * email_checkout_subj_user: email subject to user
  * email_checkout_subj_admin: email subject to admin
  * email_checkout_admin_txt: txt notification to the admin that a customer made a purchease
  * email_checkout_admin_html
  * email_checkout_address_txt: here you have to add your companies address. This gets added to some emails
  * email_checkout_address_html
  * email_cancel_order_user_txt: email to the customer when he cancels an order
  * email_cancel_order_user_subj
  * email_cancel_order_user_html
  * checkout_thankyou_wire: the text shown on the checkout thank you page when wire transfer is selected as gateway
  * checkout_thankyou_paypal: same as above for paypal
  * checkout_thankyou_cod: same as above for cash on delivery
  * checkout_thankyou_page: general text that applies to all gateway methods


===== About =====
abouts

===== cpgShop config=====
config: see above

===== Order Manager =====
The order manager is the main part of this shopping cart system. Here you can see and set the status of the orders, mark them paid, sent or printed.

If a customer made an order, then you can see this order in the order manager. In the main view you see an overview of all new, incoming orders. Small icons indicate if the order's paid, printed, sent, downloaded and if you have clicked it once.

When you've enabled in config 'auto move on state change', then the orders get sorted automatically into the right folder. In the table header you can select what virtual folder (order state) to view. Possible values are all, incoming, booked, printed (if enabled in config), processed. Click an order to go to the detail view and work on that order.

Here you can see the customers billing and shipping address and if he entered some additional notes when checking out. You'll see a link to the users profile and his email address.


The main part of the detail view is below the billing address in the 'Information:' box. Here you can set the differnt order states. If a user has paid (eg. by wire and you've seen the funds in your bank account, then you click the set button next to the (b)ooked icon). The booked flag goes green and if enabled in config, the customers sent a state changed email (paid).
If it's a to download cart, then click '(Re)create download directory' and the download directory's getting created for the customer. He'll get sent an email with his username, password and link to download the content.

If you use PayPal IPN this all happens automatically. You just log in if something goes wrong or to check the processed orders.
In case you sell to print pictures, then there are the mentioned other order states to help you manage the orders.


In that information box you can see a lot more useful information like info about the cart, if it is to ship or if it's a download. Also displayed is the download date and time. You probably need information about the gateway method, the delivery method, the PayPal IPN status and the PayPal fee, too.


Below that area are the action buttons. About one we already talked, the (Re)create download directory button. If a user couldn't log in or hasn't received his download details, you can chose to recreate this download directory. The old htaccess and htpassword files get overwritten. If you want the user to keep his old password you just can hit the 'resend password' button.

Maybe you sometimes want to lock the download directory, then hit the lock download directory button. However the directory must exist. If it hasn't been created first, then you are not able to lock it. Other buttons you can find here are 'delete download diorectory', 'resend invoice' and 'PayPal IPN log'.


The order history is an area accessible by the customer. It is similar to the order manager just way stripped down. The customer can see his orders and the details he entered while checking out. Also possible for him is, to see the order states. If the customer hasn't paid, payment info shows up, too (PayPal button, wire information). The user has a resend password button and, once paid, a download order and a resend password button, too.

====== Applying price groups to images ======
To apply price and option groups to images is fairly simple. You can do that by clicking the cpgShop buttons below an intermediate image or next to an album. Here select the picture you want the price and option set applied and set these values. Now an add to cart area shows up below the intermediate image. To remove a picture from selling, uncheck it and hit 'edit'.

====== Editing required profile fields ======
cpgShop adds some new entries to the user profile like surename, last name and some address fields. That's usually important when you want to ship items to the customer. Even if you have a download shop that may be useful information (invoice). However you not might to need the country field as a mandatory field. So just open the language file (plugins/cpgshop/lang/english.php) and scroll dwon to the very bottom. Here you see entries like
  * $lang_register_php['zip_warning1'] = 'The zip field mustn\'t be empty!';
  * $lang_register_php['zip_warning2'] = 'Zip must be at least two characters long!';
Some have double slashes in front - that means, that these are not mandatory whilst the not commented out ones are. I bet you know now what to do.

====== Bridging ======
The shop should work with a bridged Coppermine but haven't tested that. The main difference is, that all I have said above required fields doesn't apply here. It's not as comfortable for the customer as he needs to register within the bridge application. Here I have no possibilities to modify that process. So once registered and logged in, the address input is done for the native Coppermine user but not for the bridged Coppermine user. Here the customer has to enter his address in the checkout process.


====== SSL certificates and keys ======
To use encrypted PayPal buttons you need to create a public SSL ceritificate and a private key. For that you need openssl installed on your home computer. On a nix box search it using which openssl. Windows user can download it -> [[http://www.openssl.org/|OpenSSL]]


Now open a console and browse to the directory where you installed openssl, eg. on a Windows box C:\openssl\bin. Here type:
  * openssl genrsa -out own_privk.pem 1024
to generate your private key. Never give that key away. When done create the public cert with:
  * openssl req -new -x509 -key own_privk.pem -out own_pubk.pem -days 365

If that spits out error messages, you probably have to add the path to the openssl config file. In the above example that'll be -config c:\openssl\share\openssl.cnf. Answer the questions and you're done with the key generation. Just move the cert and the key to the place where you store your keys. By default that is for cpgShop the plugins/cpgshop/keys directory. However I suggest to use a directory that's not accessible by the web.


Now log into your paypal merchant account. If you test things in the paypal sandbox than use that. Click the profile subtab and in the right column (seller preferences) goto encrypted payment settings. Now click add and browse to your just created public cert own_pubk.pem and upload it. If it uploads successfully it will appeare on the next screen under your public certificates. Now copy the CERT ID and enter it into the cpgShop config (PayPal settings -> CERT ID).


Finally download PayPals public certificate. Again you find it in the profile subtab, seller preferences, encrypted payment settings. Click download in the PayPal public cert area and save it in the folder where you have stored your public and private key.


If you're already here it is highly recommended to block traffic from non encrypted buttons. Profile subtab, Website Payment Preferences, select Block Non-encrypted Website Payments and save.


And don't forget to enable encrypted PayPal buttons in the Shops config.


